PyVistaとSphinx#
PyVistaを活用して,素晴らしいインタラクティブなWebドキュメントを作成することができます.
ちなみに
このチュートリアルのセクションは,PyVistaドキュメントの Plotting Themes と Sphinx PyVista Plot Directive の章から採用されたものです.
ドキュメントに3Dプロットを動的に生成する#
PyVistaを使うと, Matplotlib plot_directive と同じように,Sphinx内で静的または動的な画像を直接生成することができます.手動でプロットを作成して,コードセクションの後に追加するのではなく,代わりに動的に画像を生成して,ドキュメントの中に直接埋め込むことができるのです.これは sphinx-gallery ともシームレスに動作しますので, Matplotlib Example Gallery のようなノートブックのサンプルを作成することができます.
さらに副次的な利点として,生成したドキュメントがプロジェクトの API と一致することを確認できます.これを GitHub ワークフロー に組み込むと,次のようになります.
このセクションでは,以下の項目について説明します.
静的プロット - Sphinx PyVista プロットディレクティブ#
Sphinxを使用してドキュメントをビルドする際に, conf.py に以下を追加すると, pyvista-plot ディレクティブを使用して,sphinx内でPyVistaプロットの静止画像を生成することができます.
extensions = [
"sphinx.ext.napoleon",
"pyvista.ext.plot_directive",
]
そうすれば,sphinxのドキュメントファイルの中で,plottingディレクティブを発行することができます:
.. pyvista-plot::
:caption: A sphere
:include-source: True
>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> out = sphere.plot()
以下のように表示されます.
>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> out = sphere.plot()
これはデフォルトの球体#
Jupyter Sphinx拡張を使った動的プロッティング#
PyVistaは jupyter-sphinx 拡張もサポートしています.この拡張機能を使うと, jupyter-execute ディレクティブを使って,sphinx *.rst ファイル内のコードブロックを実行することができます:
.. jupyter-execute::
name = 'world'
print('hello ' + name + '!')
以下のように表示されます:
name = 'world'
print('hello ' + name + '!')
hello world!
同様に,通常ノートブック内でレンダリングされるPyVistaからの出力は, jupyter-execute ディレクティブの出力セルにレンダリングされます.例えば, pythreejs バックエンドを使用したプロットは次のようになります.
.. jupyter-execute::
from pyvista import examples
dataset = examples.download_urn()
dataset.plot(color='tan', jupyter_backend='pythreejs', window_size=(700, 400))
以下のように表示されます:
from pyvista import examples
dataset = examples.download_urn()
dataset.plot(color='tan', jupyter_backend='pythreejs', window_size=(700, 400))
PyVistaで Panel バックエンドを使用する#
PyVistaは vtk.js jupyterlab plotting backendとして panel <https://github.com/holoviz/panel>`_ libraryの使用をサポートしています.このライブラリは,スタンドアロンのVTKビューアとして,あるいは緊密に連携した ``pyvista plotting backendとして使用することが可能です. 例えば,Jupyterノートブック環境では, plot や Plotter.show に jupyter_backend='panel' を渡すと,自動的にJuptyerと panel でプロットできるようになります.
例えば,これは PyVista のロゴです:
.. jupyter-execute::
from pyvista import demos
demos.plot_logo(background='white', jupyter_backend='panel')
以下のようにドキュメント内に表示されています:
from pyvista import demos
demos.plot_logo(background='white', jupyter_backend='panel')
使用例と使用方法#
Jupyterノートブック内で panel を使用するには2つの方法があります. mesh.plot() で jupyter_backend を設定することにより,プロットごとに使用することができます.
.. jupyter-execute::
import pyvista as pv
from pyvista import examples
# create a point cloud from lidar data and add height scalars
dataset = examples.download_lidar()
point_cloud = pv.PolyData(dataset.points[::100])
point_cloud['height'] = point_cloud.points[:, 2]
point_cloud.plot(window_size=[500, 500],
jupyter_backend='panel',
cmap='jet',
point_size=2,
background='w')
そして,これがSphinxでの出力結果です:
import pyvista as pv
from pyvista import examples
# create a point cloud from lidar data and add height scalars
dataset = examples.download_lidar()
point_cloud = pv.PolyData(dataset.points[::100])
point_cloud['height'] = point_cloud.points[:, 2]
point_cloud.plot(window_size=[500, 500],
jupyter_backend='panel',
cmap='jet',
point_size=2,
background='w')
または,プロットバックエンドとグローバルテーマを設定するコードを最初に隠すことができます:
.. jupyter-execute::
:hide-code:
import pyvista as pv
# Set the global jupyterlab backend. All plots from this point
# onward will use the ``panel`` backend and do not have to be
# specified in ``show``
pv.set_jupyter_backend('panel')
そして,任意のデータセットに対して plot を直接実行するようにします:
.. jupyter-execute::
from pyvista import examples
dataset = examples.download_dragon()
dataset.plot(cpos="xy")
以下のように見えます:
from pyvista import examples
dataset = examples.download_dragon()
dataset.plot(cpos="xy")